Working with Maestro Web Services
3.1 Requirements for Client Development.
The data extraction APIs were designed with ease of use and scalability in mind. For this reason,
they use the industry standard HTTPS protocol (See RFC 2616) as their baseline. Most operating
systems and programming languages support this protocol out of the box, with nearly universal
support available with third party libraries.
3.1.1 Programming Tools and Libraries.
Any programming language, tool, or library that can make HTTPS requests can be used
to communicate with the data extraction service.
3.2 Authentication
Maestro web services authenticate using the HTTPS Basic authentication model. Each request
made to the web services will require that the appropriate credentials be passed in the
“Authorization” header of the request as described in RFC 2617.
Notes:
The LMS account used for authentication must be assigned a role that has permission to create
custom reports.
In the LMS Password Security / Password Policy Settings, the Admin Pw Life Time field
determines the number of days for which an administrator's password will remain valid. After
this number of days elapses, the password will expire. Data extraction will not work for an
account whose password has expired. To prevent an interruption in data extaction, you will want
to update passwords within the specified time. An option would be to set the Admin Pw Life
Time to a large number like 9999 (days) so password changes would be infrequent. However, the
number of days between password changes should be based on your organization’s security
policy.

Excerpted from RFC 2617:
2 Basic Authentication Scheme

   The "basic" authentication scheme is based on the model that the
   client must authenticate itself with a user-ID and a password for
   each realm.  The realm value should be considered an opaque string
   which can only be compared for equality with other realms on that
   server. The server will service the request only if it can validate
   the user-ID and password for the protection space of the Request-URI.
   There are no optional authentication parameters.

   For Basic, the framework above is utilized as follows:

      challenge   = "Basic" realm
      credentials = "Basic" basic-credentials

   Upon receipt of an unauthorized request for a URI within the
   protection space, the origin server MAY respond with a challenge like
   the following:

      WWW-Authenticate: Basic realm="WallyWorld"

   where "WallyWorld" is the string assigned by the server to identify
   the protection space of the Request-URI. A proxy may respond with the
   same challenge using the Proxy-Authenticate header field.

   To receive authorization, the client sends the userid and password,
   separated by a single colon (":") character, within a base64 [7]
   encoded string in the credentials.

      basic-credentials = base64-user-pass
      base64-user-pass  = <base64 [4] encoding of user-pass,



Franks, et al.              Standards Track                     [Page 5]

RFC 2617                  HTTP Authentication                  June 1999


                       except not limited to 76 char/line>
      user-pass   = userid ":" password
      userid      = *<TEXT excluding ":">
      password    = *TEXT

   Userids might be case sensitive.

   If the user agent wishes to send the userid "Aladdin" and password
   "open sesame", it would use the following header field:

      Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

General workflow
All of the data extraction services follow the same overall flow. This example will request a
transcript file, but is applicable to all file types.
1) Post a request to the URL for the file you're requesting:
POST /data/{domain}/transcript
2) The server will respond with a “201 Created”
3) Upon a successful request, the “Location” header will contain the URL at which the file can
be found:
Location: /data/transcripts/{transcript-filename}.csv
4) Perform a GET request for the file found in #3:
GET /data/transcripts/{transcript-filename}.csv
This will download the file containing the transcript information.

3.3.1 The initial POST
The initial request to create a file will be in the form of an HTTP post. The content type
for the form should be application/x-www-form-urlencoded and contain any
filtering parameters in the body of the request. The parameters available are described in
detail for each file type.
After receiving the response, the HTTP status code can be interrogated to determine the
outcome of the request. At the time of this writing, the current valid values are:
201 Created: The receipt of this status indicates that the data extraction process was
successful and that a file has been created for you. When a 201 is received, the 'Location'
header in the HTTP response will contain the URL of the newly created file.
400 Bad Request: The receipt of this status indicates that there was a validation
error while attempting to process the request. When received, the body of the response
will contain validation errors encountered. Correct the validation errors and resubmit the
request.
500 Internal Server Error: The receipt of this status indicates that there was a
server side error while generating the file. If this is received, retry the request at a later
time. If the problem persists, contact GeoLearning with recreation steps.

3.3.2 GETting the requested data.
Once you have received a successful POST response, your file is available for download.
To download the file, simply issue a GET request on the URL found in the 'Location'
header stated above. The file will be available for 3 days from it's creation date.
Possible values for this status are as follows:
200 Ok: The receipt of this status indicates that the file was requested successfully. The
message body contains the actual content.
302 Found: The receipt of this status indicates that the file can be accessed via another
URL. This is typically only received when switching between HTTP and HTTPS
protocols and should be honored. If received, simply issue the GET request again, using
the URL found in the 'Location' header of the response.
404 Not Found: The receipt of this status indicates that the file no longer exists at this
location. This is likely caused by the age off process removing the files after they have
expired.

